home *** CD-ROM | disk | FTP | other *** search
/ Programming Sound Cards / Programming Sound Cards.iso / sound_55 / ruckdac.doc < prev    next >
Text File  |  1995-01-01  |  94KB  |  3,921 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.      RUCKUS-DAC Copyright (C)1993 Cornel Huth
  8.      Documentation Copyright (C)1993 Cornel Huth
  9.      All Rights Reserved.
  10.  
  11.      Version 1.0d.
  12.      18-Oct-93/C.
  13.  
  14.      For ordering information, license agreement, and product support
  15.      information, see Appendix Z.
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.      Introduction
  74.  
  75.      RUCKUS-DAC is one part of the RUCKUS sound toolkit for DOS programmers. Its
  76.      forte is its ability to play digital data in three different formats and
  77.      record in two: VOC, WAVE, and MOD. The other part of the RUCKUS sound
  78.      toolkit is RUCKUS-MIDI. Its forte is its ability to play standard MIDI data
  79.      files. See RUCKUS-MIDI for more.
  80.  
  81.      RUCKUS-DAC currently supports six sound devices: the PC speaker, a DAC on
  82.      an LPT port, Disney Sound Source, AdLib MSC, Sound Blaster, and the Sound
  83.      Blaster Pro (stereo). Since most sound devices emulate one of the above,
  84.      RUCKUS-DAC should handle most devices likely to be found in a PC. RUCKUS-
  85.      DAC is implemented to be device-independent. As new sound hardware (with
  86.      supporting documentation) becomes available to this programmer, it will be
  87.      added. The code you write to play any of the digital formats using RUCKUS
  88.      will play on any new device added later without any code changes to your
  89.      program. You just supply the new device ID (see InitDac for more). 
  90.  
  91.      The RUCKUS toolkit supports most DOS compilers as is. This documentation
  92.      describes using RUCKUS with C DOS compilers. Also available is a BASIC-
  93.      specific version (BASIC7/QB45/VBDOS/etc.) of this documentation. Other
  94.      implementations should be able to get the necessary details using this
  95.      documentation. Note that these toolkits will not work with the current or
  96.      past Turbo Pascal compilers. This is due to Turbo Pascal's proprietary
  97.      linkage methods.
  98.  
  99.      To provide compiler-independence, RUCKUS (and all of my latest toolkits)
  100.      implements a simple calling scheme: a single far pointer (segmented) is
  101.      passed to RUCKUS. The data structure that is pointed to varies depending on
  102.      RUCKUS function. There are 13 structure types ("packs") currently. The
  103.      first two data members of each pack are identical in all packs. These are
  104.      Func and Stat. The remaining members, if any, vary depending on
  105.      requirements. For instance, the LoadDac routine uses, in addition to Func
  106.      and Stat, six additional members: FilenamePtr, StartPos, LoadSize, XMMflag,
  107.      XMMhandle and LoadPtr. The steps needed to load a digital (LoadDac is for
  108.      VOC/WAVE files, LoadMod is for MOD files) data file to memory would be as
  109.      follows:
  110.  
  111.  
  112.           1. Allocate pack. Packs are reusable and can be allocated any way you
  113.           want. Here we make a static allocation for simplicity.
  114.  
  115.           struct LoadPack LP;
  116.  
  117.           2. Assign member values:
  118.       
  119.           gets(filename);
  120.           LP.Func = LoadDac;
  121.           LP.FilenamePtr = filename;
  122.           LP.StartPos = 0L;                    
  123.           LP.LoadSize = 0L;
  124.           LP.XMMflag = 0;  
  125.  
  126.           3. Call RUCKUS:
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.           rez = RUCKDAC(&LP);
  141.  
  142.           4. On return from the call:
  143.  
  144.           if (rez == 0)
  145.              // LP.LoadPtr -> address of digital data in memory
  146.              // or, if XMMflag then LP.XMMhandle is XMS handle of storage 
  147.  
  148.      After the load you can immediately call the PlayDac routine using the
  149.      LP.LoadPtr returned from the LoadDac call. You don't need to use the RUCKUS
  150.      LoadDac routine; you can perform your own digital data file loads to memory
  151.      (VOC and WAV only, MODs must be loaded by RUCKUS-DAC). However, RUCKUS can
  152.      load up to 32 separate digital files at one time (and 96 more to XMS) and
  153.      performs all the necessary memory allocations and deallocations
  154.      automatically. See LoadDac/LoadMod for more.
  155.  
  156.      As you can see, using RUCKUS is easy. If you'd rather use a traditional 
  157.      calling convention, wrap the RUCKUS routines in a C function and call it as
  158.      you normally would, e.g., rez = LoadDacFile(filename,LP) where LoadDacFile
  159.      contains the actual code (as shown above).
  160.  
  161.      Now that I have your interest, let me tell you why I've provided this
  162.      toolkit for you. Shareware. That's right. Shareware. What I've done is
  163.      provide you with a means to evaluate this product completely, with no
  164.      upfront obligations. If you can't make use of this product, no problem.
  165.      Think of this as the ultimate return policy. You can actually take the
  166.      goods home, try it out, break it in. Then, if after a period of no more
  167.      than 21 days, you feel that this product is well worth the price I'm
  168.      asking, by all means, you should go ahead and fill out the order form and
  169.      send it in. If you do not register, then of course, it means the product is
  170.      not something you can use. If you can't use it, I don't want your money.
  171.      But if it's something you will use, it's only fair that you register. The
  172.      PROFESSIONAL registered versions does not have any built-in advertising
  173.      screens. The PERSONAL DEVELOPER registered version does display a sign-on
  174.      banner once. See Appendix Z. for ordering options and other related
  175.      information specific to this product.
  176.  
  177.      The documentation that follows describes each of the function routines as
  178.      to use, pack type used, and sample code in C. Also available is a BASIC
  179.      version of this toolkit, differing only in example programs and
  180.      documentation. For additional source examples see the included X files on
  181.      disk.
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.      RUCKUS-DAC Functions.
  206.  
  207.       0. SysInfoDac  ...........................................  5
  208.       1. InitDac  ..............................................  6
  209.       2. ExitDac  ..............................................  7
  210.       3. AtExitDac  ............................................  8
  211.       4. LoadDac  ..............................................  9
  212.       5. PlayDac  .............................................. 10
  213.       6. RecordDac  ............................................ 11
  214.       7. StoreDac  ............................................. 13
  215.       8. EndDac  ............................................... 14
  216.       9. PauseDac  ............................................. 15
  217.      10. DeallocDac  ........................................... 16
  218.          11 to 19 are not used 
  219.      20. SetAllDac  ............................................ 17 
  220.      21. SetVolumeDac  ......................................... 19
  221.      22. SetIntRateDac  ........................................ 20
  222.      23. SetPriorityDac  ....................................... 21
  223.          24 to 27 are not used
  224.      28. GetBufferDataDac  ..................................... 22
  225.      29. GetBytePosDac  ........................................ 23
  226.      30. SetAllSBP  ............................................ 24
  227.      31. SetVolMainSBP ......................................... 26
  228.      32. SetVolVocSBP  ......................................... 27
  229.      33. SetLevelMicSBP  ....................................... 28
  230.      34. SetLevelCDSBP   ....................................... 29
  231.      35. SetLevelLineSBP  ...................................... 30
  232.      36. SetFilterOutSBP  ...................................... 31
  233.      37. SetFilterInSBP  ....................................... 32
  234.      38. SetSourceSBP  ......................................... 33
  235.      39. SetStereoSBP  ......................................... 34
  236.      40. SetSpeakerSB  ......................................... 35
  237.          41 to 47 are not used
  238.      48. GetMixerRegSBP  ....................................... 36
  239.      49. GetDacSB .............................................. 37
  240.      50. ExitMod  .............................................. 38
  241.      51. AtExitMod  ............................................ 39
  242.      52. LoadMod  .............................................. 40
  243.      53. PlayMod  .............................................. 41
  244.      54. EndMod  ............................................... 42
  245.      55. PauseMod  ............................................. 43
  246.      56. SetIntRateMod ......................................... 44
  247.      57. SetSpeedMod ........................................... 45
  248.      58. SetVolumeMod  ......................................... 46
  249.      59. SetPositionMod ........................................ 47
  250.      60. SetStereoMod .......................................... 48
  251.      61. SetFastMod ............................................ 49
  252.          Appendix A. Tips and Tricks ........................... 50
  253.          Appendix B. Pack Structure ............................ 51
  254.          Appendix C. Compiler, Linker and Call Use ............. 55
  255.          Appendix D. RUCKUS-DAC Data Area ...................... 56
  256.          Appendix Z. Ordering Information, License Agreement
  257.                      and Product Support........................ 58
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.      SysInfoDac          Func: 0        Pack: SysInfoPack
  272.  
  273.      Before doing any other RUCKUS function, you should call SysInfoDac to
  274.      determine what sound devices are available. RUCKUS-DAC currently supports
  275.      the following devices:
  276.  
  277.           0. PC speaker
  278.           1. LPT-DAC device on a printer port, commonly home-built
  279.           2. Disney Sound Source, a printer port DAC device
  280.           3. AdLib Music Synthesizer Card
  281.           4. Sound Blaster (DSP version 1.03 and up)
  282.           5. Sound Blaster Pro
  283.           6. UltraSound*
  284.  
  285.      *The UltraSound (GUS) will be supported in an upcoming release. PAS16
  286.      native support soon after.
  287.  
  288.      Since many current sound cards are Sound Blaster compatible, RUCKUS-DAC
  289.      supports somewhere around 95% of all sound devices in active use on PC-
  290.      compatible computers.
  291.  
  292.      SysInfoDac scans for and detects all devices. In the case of the DAC on the
  293.      printer port (LPT-DAC), it can only detect if a printer port is available.
  294.      All other sound cards are detected by their manufacturer's documented
  295.      methods, and should be 100% reliable. Information returned includes the
  296.      device's base port address, IRQ line, DMA channel, and capabilities.
  297.  
  298.      Since the SB Pro is SB-compatible, and since the SB is AdLib-compatible,
  299.      these lower devices are also detected in these cards.
  300.  
  301.  
  302.      Sample Use:
  303.  
  304.      struct SysInfoPack SIP;
  305.  
  306.      SIP.Func = SysInfoDac;   //SysInfoDac is a CONST in RUCKDAC.BI
  307.      rez = RUCKDAC(&SIP);     //call to RUCKUS library code
  308.      if (rezt == 0) {
  309.         printf("CPU type is %u/%u\n", SIP.CPU, SIP.MHz);
  310.         if (SIP.SD[5].Device != 0)
  311.             printf("SB PRO at port %x\n", SIP.SD[5].Port);
  312.         if (SIP.SD[4].Device != 0)
  313.             printf("SB 1.5 at port %x\n", SIP.SD[4].Port);
  314.         :
  315.         printf("PC speaker always available\n");
  316.      }
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                                                                5
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.      InitDac             Func: 1        Pack: InitPack
  338.  
  339.      Before you can use a sound device, you must inform RUCKUS about it. The
  340.      InitDac routine sets up default sets of data that RUCKUS uses, or that you
  341.      can later change. You cannot operate a device until you have called this
  342.      routine. You should not InitDac more than one sound device at a time. If
  343.      you want to use a different device, first ExitDac then InitDac again.
  344.  
  345.      The information that InitDac requires is available from the SysInfoDac
  346.      routine. InitDac returns with information on its data section address and
  347.      size, and the address of the ExitDac routine (in case AtExitDac doesn't
  348.      work for your esoteric compiler or run-time library).
  349.  
  350.      InitDac is used for both RUCKUS-DAC and the RUCKUS-DAC mod extension code.
  351.  
  352.      There is a special feature available for the PC speaker and the AdLib
  353.      devices: 2x upsampling. To use 2x upsampling, use the I/O port as returned
  354.      by SysInfoDac for IP.IOport. To use standard (in some cases downsampling)
  355.      play for the PC speaker and AdLib (recommended for play of samples with
  356.      rates above 8kHz) use an IP.IOport=0. For an example of 2x upsampling see
  357.      the MODAC1 documentation. Upsampling is available only for VOC and WAVE
  358.      playback.
  359.  
  360.  
  361.      Sample Use:
  362.  
  363.      struct InitPack IP;  
  364.  
  365.      IP.Func = InitDac;       // CONST in RUCKDAC.BI
  366.      IP.DeviceID = device;    // see SysInfoDac for device numbers
  367.      IP.IOport = port;        // and other info needed by InitDac
  368.      IP.IRQline = IRQ;
  369.      IP.DMAch = DMA;
  370.      rez = RUCKDAC(&IP);
  371.      if (rez == 0)
  372.         // device initialized okay
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                                                                6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.      ExitDac             Func: 2        Pack: XitPack
  404.  
  405.      When using RUCKUS, certain aspects of the computer are controlled by the
  406.      RUCKUS code. To have RUCKUS return full control back to the computer and
  407.      operating system, ExitDac must be called. To ensure that this happens, even
  408.      after an abnormal termination (such as an untrapped divide by zero), RUCKUS
  409.      provides a routine that ensures that ExitDac is always called before your
  410.      application ends. See AtExitDac for more.
  411.  
  412.      Once a sound device has been initialized with InitDac, you must call
  413.      ExitDac before you can switch to another device with InitDac. Calling
  414.      ExitDac releases any memory allocations made while the previous sound
  415.      device was active (allocations made by LoadDac, LoadMod, or RecordDac).
  416.      Memory allocations that your program has made on its own are not affected.
  417.  
  418.      Tip: If you call InitDac with one device, load a file, then call InitDac
  419.      again with another device, the memory allocated by the load is not
  420.      released. This allows you to play data from previous load operation(s) on
  421.      all the RUCKUS-supported devices. To force the release of a previous memory
  422.      allocation, see DeallocDac. 
  423.  
  424.  
  425.      Sample Use:
  426.  
  427.      struct XitPack XP;
  428.  
  429.      XP.Func = ExitDac;
  430.      rez = RUCKDAC(&XP);
  431.      if (rez != 0)
  432.         // error
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.                                                                                7
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.      AtExitDac           Func: 3        Pack: XitPack
  470.  
  471.      To ensure that all machine control is returned to the operating system and
  472.      that all RUCKUS-made memory allocations are released before your
  473.      application program ends, AtExitDac should be used. This routine takes
  474.      advantage of most compiler's _atexit enregistration routine. This _atexit
  475.      compiler run-time library routine allows for up to 32 different calls to be
  476.      made just prior to it (the compiler's run-time code) returning to the
  477.      operating system (program termination). Most of the time, you can make all
  478.      the necessary shutdowns that your program requires in your app's code.
  479.      However, abnormal terminations -- terminations that can cause a bypass of
  480.      your own shutdown code -- may mean that when the operating systems regains
  481.      control, certain machine operations are not in a stable state. The
  482.      AtExitDac routine ensures that ExitDac is called no matter what (in most
  483.      all cases, except where the program locks up, in which case the session
  484.      needs to be reset anyway). 
  485.  
  486.      Note: AtExitDac should be called only once in your program's execution. 
  487.  
  488.      Graphically, your program executes like this:
  489.  
  490.         DOS C>program.exe
  491.           |
  492.         Compiler startup code (performs basic setup)
  493.           |
  494.           +----->+
  495.                  | Your program starts, ends
  496.           +<-----+
  497.           |   
  498.          rest of startup code, _atexit registered routines
  499.           |
  500.          DOS C>_
  501.  
  502.      Caution: In order for the _atexit registered routines to be called by your
  503.      compilers run-time, you must not allow you program to exit via non-standard
  504.      ways. Calling INT21/4C is on example (you should never do this from
  505.      compiled code, anyway). Note that some compilers' run-time code bypasses
  506.      _atexit when Ctrl-C or Ctrl-Break is used. If this is the case, you must
  507.      trap these and perform an ExitDac before returning to DOS.
  508.  
  509.      The startup code is basically a program that sets up your program to run,
  510.      calls your program, regains control when your program ends, then performs
  511.      the necessary shutdown actions required, including calling all routines
  512.      registered with _atexit.
  513.  
  514.      Sample Use:
  515.  
  516.      struct XitPack XP;
  517.  
  518.      XP.Func = AtExitDac;
  519.      rez = RUCKDAC(&XP);
  520.      if (rez !=0)
  521.         // error (more than 32 calls made to _atexit)
  522.  
  523.  
  524.                                                                                8
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.      LoadDac             Func: 4        Pack: LoadPack
  536.  
  537.      Though not required, you can have RUCKUS load a digital file into memory
  538.      for you. It makes the necessary memory allocations and loads the data into
  539.      conventional or XMS memory. You can load up to 32 separate digital data
  540.      files to conventional memory at one time, and up to 96 more into XMS.
  541.      RUCKUS takes care of the memory allocation details.
  542.  
  543.      LoadDac can also be instructed to start loading at any particular byte in a
  544.      file for as many bytes as you specify. This would be useful, for example,
  545.      if you have a single file made up of several VOC or WAVE files appended to
  546.      form one large data file.
  547.  
  548.      Sample Use:
  549.  
  550.      struct LoadPack LP;
  551.  
  552.      LP.Func = LoadDac;
  553.      LP.FilenamePtr = filename;
  554.      LP.StartPos = 0L;         // start load at first byte of file
  555.      LP.LoadSize = 0L;         // have RUCKUS load all of it
  556.      LP.XMMflag = 0;           // -1 if loading into XMS
  557.      rez = RUCKDAC(&LP);
  558.      if (rez == 0) 
  559.         // okay load
  560.  
  561.      Note that even though loading into XMS memory, RUCKUS-DAC still needs some
  562.      conventional memory to use as a buffer. After the load to XMS, the low
  563.      memory is no longer required.
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                                                                9
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.      PlayDac             Func: 5        Pack: PlaybackPack
  602.  
  603.      Once the digital data is in either conventional or XMS memory, you can play
  604.      it to any of the RUCKUS-supported devices. XMS memory, however, requires
  605.      DMA playback mode; this mode is supported in the Sound Blasters only. Also,
  606.      for STEREO playback, DMA mode is required (SB Pro only).
  607.  
  608.      In addition to DMA-mode playback, you can instruct RUCKUS to play in the
  609.      background or foreground. Playing in the background allows your computer
  610.      program to regain control immediately after play has begun. If you choose
  611.      foreground play, control does not return to your program until the end of
  612.      the data has been played, or, until CTRL-ALT is pressed.
  613.  
  614.      All RUCKUS-supported devices can be played in the background. Only the
  615.      Sound Blasters can be played using DMA. DMA playback is similar to
  616.      background play in that control is returned to your program immediately,
  617.      but it is also much more efficient since DMA playback uses no CPU time.
  618.      Background play, on the other hand, can require anywhere from 1 to 100% of
  619.      available CPU time, depending on what playback rate has been selected (see
  620.      SetIntRateDac). 
  621.  
  622.      Since it's possible to load several data files into memory at one time, to
  623.      play a particular data file requires that you specify its start address or,
  624.      if loaded to XMS memory, its XMS handle. Given the code sequence example in
  625.      LoadDac, the following PlayDac code takes up from there:
  626.  
  627.      struct PlaybackPack PBP;
  628.  
  629.      PBP.Func = PlayDac;
  630.      PBP.Mode = 2;       // mode 0=foreground, 1=background, 2=DMA
  631.      PBP.XMMhandle = 0;  // 0=conv memory data follow, 1+=XMS data follows
  632.  
  633.      'If conventional memory used, then the following pointer is the 
  634.      'segment:offset start address of the VOC/WAVE data to play.
  635.      '
  636.      'If XMS memory used, the following pointer is the 32-bit offset within the
  637.      'XMS handle (PBP.XMMhandle) that the data starts. If you just load one data
  638.      'file to one XMM handle, then these will always=0. However, if you're short
  639.      'on available XMM handles, you could load several data files into a single,
  640.      'huge, XMM allocation. In order to do this, you must do your own data
  641.      'loads since LoadDac loads one file per XMM handle.
  642.      '
  643.      PBP.LoadPtr = LP.LoadPtr;
  644.  
  645.      'Note: the PBP.BufferSize is used by PlayMod only. Also, you may want/need
  646.      'to perform pre-Play tasks. See SetAllDac/SetAllSBP.
  647.  
  648.      rez = RUCKDAC(&PBP);
  649.      if (rez == 0)
  650.         // if DMA or background mode then the digital data is playing now, 
  651.         // but if foreground mode, the play has ended by the time we get here
  652.  
  653.  
  654.  
  655.  
  656.                                                                               10
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.      RecordDac           Func: 6        Pack: RecordPack
  668.  
  669.      The Sound Blasters can record as well as play digital data. As with play,
  670.      you can record directly into conventional or XMS memory. You can let RUCKUS
  671.      make the memory allocations, or you can allocate your own memory and record
  672.      into that. With the SB Pro, you can also record in stereo.
  673.  
  674.      With the Sound Blaster Pro you can select among three input sources: mic,
  675.      line, and CD. The earlier Sound Blaster has one input, the mic. A quality
  676.      microphone can make a big difference. For other-than-mic input on the SB,
  677.      you can pipe the headphone output of a CD player into the mic input. Your
  678.      results may vary, but this is better than mic'ing a loudspeaker. For
  679.      anything other than mic input, the SB Pro is recommended. Its recording
  680.      quality is very good since it allows sampling rates up to 45.5kHz in mono,
  681.      and 22.75kHz in stereo. The SB allows recording sampling rates up to 12kHz
  682.      (rated to 13kHz record and 23kHz playback). The sampling size is 8 bits.
  683.  
  684.      NOTE: TO RECORD IN STEREO AT A GIVEN SAMPLE RATE, YOU MUST SPECIFY TWICE
  685.            THE RATE DESIRED. FOR EXAMPLE, TO RECORD OFF A CD DECK CONNECTED TO
  686.            THE LINE INPUT OF THE PRO, AT A SAMPLE RATE OF 22.5kHz, YOU MUST
  687.            SET THE SP.SetIntRate=44100.
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.                                                                               11
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.      Sample Use:
  735.  
  736.      struct RecordPack RP;
  737.      struct XitPack XP;   
  738.      EP.Func = EndDac;         // preload EP.Func here for space reasons
  739.  
  740.      RP.Func = RecordDac;
  741.      RP.SampleRate = 23000;
  742.  
  743.      /* To record into XMM and have RUCKUS make the allocation, set RP.XMMhandle
  744.      to -1. If you made your own XMS allocation, set this to your handle.
  745.      To load into conventional memory and have RUCKUS make the allocation,
  746.      set RP.RecordPtr to NULL. If you made your own allocation, set this
  747.      to your far segmented pointer. */
  748.  
  749.      RP.XMMhandle = 0;         // use conventional memory if this is 0
  750.      RP.RecordPtrOff = 0;      // have RUCKUS make the memory allocation
  751.      RP.RecordPtrSeg = 0;      // if this is 0 (and if RP.XMMhandle=0)
  752.  
  753.      /* By using the DACDATA.MemDOS or .MemXMM, we can record as many bytes
  754.      as we have available. Below we reserve 5K (more for XMS) for misc use, as
  755.      you should, too. This is the max bytes to record; we can also stop
  756.      at any point before this. */
  757.  
  758.      RP.RecordBytes = (DACDATA.MemDOS - 5) * 1024;  
  759.      RP.StereoFlag = 0;
  760.      rez = RUCKDAC(&RP);
  761.      if (rez == 0)  {
  762.         // we are recording right now, using DMA, so, while we could do just
  763.         // about anything we wanted, in this example, we just wait until the
  764.         // record is over
  765.  
  766.         do 
  767.            ;
  768.         while (DACDATA.End == 0);
  769.         rez2 = RUCKDAC(&XP);   // stop recording (XP defined/assigned above)
  770.      }
  771.  
  772.      /* The above loop won't be exited until all the bytes requested have been
  773.      recorded. The number of bytes recorded (not counting any file headers added
  774.      by StoreDac) is in DACDATA.RecordLen.
  775.  
  776.      Now you can save the data by using StoreDac, or play it using PlayDac. On
  777.      return from the RECORD, RP.RecordPtr is set to the segment:offset of the
  778.      first byte recorded in conventional memory, or if using XMS memory,
  779.      RP.XMMhandle is set to the XMS handle. */
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.                                                                               12
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.      StoreDac            Func: 7        Pack: SaveDataPack
  800.  
  801.      Once digital data has been loaded or recorded in memory, you can store it
  802.      do disk in either VOC or WAVE format. If you want, you can load a file in
  803.      one format and save it in the other with just a few lines of code (shown
  804.      below).
  805.  
  806.      Sample Use:
  807.  
  808.      struct SaveDataPack SDP;
  809.  
  810.      SDP.Func = StoreDac;
  811.      SDP.FilenamePtr= filename;
  812.  
  813.      // the LP pointer below is from (say) a just-loaded VOC file (using
  814.      // LoadDac), and we want to convert and store it to WAVE format
  815.  
  816.      SDP.DataPtr = LP.LoadPtr // segment:offset of conventional memory
  817.                               // or 0 if storing from an XMS handle
  818.      SDP.FileType = 2;        // 1=VOC, 2=WAVE
  819.      SDP.XMMhandle = 0;       // 0 if DOS data, else XMS handle 
  820.      rez = RUCKDAC(&SDP);
  821.      if (rez == 0)
  822.         // data stored to filename$
  823.      else
  824.         //file save error in stat
  825.  
  826.      /* Caution: Be sure to account for the additional memory required once data
  827.      has been stored to a file. StoreDac builds the appropriate VOC or WAV
  828.      header and this adds to the total memory required to reload. I suggest that
  829.      you do not record so much data as to not be able to load it back in once
  830.      saved to VOC or WAVE format. */
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.                                                                               13
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.      EndDac              Func: 8        Pack: XitPack
  866.  
  867.      EndDac is used to end (stop) play or record on command. Once PlayDac has
  868.      started, it continues to play in the background until either the end of the
  869.      digital data has been reached, or you call this routine. In the case of a
  870.      record, play continues until the number of bytes requested has been
  871.      recorded, or this routine is called.
  872.  
  873.      Sample Use:
  874.  
  875.      struct XitPack XP;
  876.  
  877.      // LoadDac and PlayDac, or RecordDac, have already been called
  878.      // see those routines for more information
  879.  
  880.      XP.Func = EndDac;     // if play or record is active this call
  881.      rez = RUCKDAC(&XP);   // ends it
  882.  
  883.      // See RecordDac on getting the number of bytes actually recorded
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.                                                                               14
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.      PauseDac            Func: 9        Pack: PausePack
  932.  
  933.      PauseDac allows you to temporarily pause and then restart a playback.
  934.  
  935.  
  936.      Sample Use:
  937.  
  938.      struct PausePack PP;
  939.  
  940.      PP.Func = PauseDac;
  941.      PP.Pause = 1;        // non-zero pauses, zero restarts
  942.      rez = RUCKDAC(&PP);
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.                                                                               15
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.      DeallocDac          Func: 10       Pack: DeallocPack
  998.  
  999.      If you have RUCKUS load digital data files, which is most likely the case,
  1000.      it makes memory allocations from the operating system memory pool. RUCKUS
  1001.      tracks up to 32 consecutive DOS loads, and up to 96 loads to XMS (provided
  1002.      enough memory and XMS handles). These should be higher than you'll ever
  1003.      likely use at one time. DeallocDac "unloads" files that RUCKUS has loaded,
  1004.      thus releasing the memory that they used. 
  1005.  
  1006.      As an example, let's say that you want to start up your program with 5
  1007.      digital data files in XMS memory. You have 5MB of XMS available. Each data
  1008.      file is 1M in size. To load a new data file after these 5, you will need to
  1009.      unload one of the 5 already loaded. DeallocDac does that for you. The
  1010.      following example loads a single data file to XMS then immediately unloads
  1011.      it.
  1012.  
  1013.      DeallocDac is not used for releasing LoadMod allocations. 
  1014.  
  1015.      Sample Use:
  1016.  
  1017.      struct LoadPack LP;
  1018.      struct DeallocPack DP;
  1019.  
  1020.      LP.Func = LoadDac;
  1021.      LP.FilenamePtr = filename;
  1022.      LP.StartPos = 0L;
  1023.      LP.LoadSize = 0L;   
  1024.      LP.XMMflag = 1;        // non-zero means use XMS for load
  1025.      rez = RUCKDAC(&LP);
  1026.  
  1027.      if (rez == 0) {
  1028.         DP.Func = DeallocDac;
  1029.         DP.HandSeg = LP.XMMhandle; // XMM handle returned by RUCKDAC(LP)
  1030.         DP.TypeFlag = LP.XMMflag;  // 0=DOS allocation, 1=XMS
  1031.         rez = RUCKDAC(&DP);     // if this were a DOS allocation, DP.HandSeg
  1032.                                 // would be set to LP.LoadPtrSeg only since
  1033.                                 // _FP_OFF(LP.LoadPtr)==0 as returned by LoadDac
  1034.      }
  1035.      if (rez != 0)
  1036.         // file load error or deallocate error in rez
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.                                                                               16
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.      SetAllDac           Func: 20       Pack: SetPack
  1064.  
  1065.      This routine sets the overall playback volume, interrupt rate, and RUCKUS
  1066.      priority in one call.
  1067.  
  1068.      The playback volume affects VOC or WAVE output for non-DMA mode, only. In
  1069.      other words, it's for controlling the volume on the PC speaker, LPT-DAC,
  1070.      Disney Sound Source, and AdLib only. To control the playback volume of the
  1071.      Sound Blaster, you must operate it under non-DMA mode. To control the
  1072.      playback of the Sound Blaster Pro, a separate set of RUCKUS routines are
  1073.      used. See the SetAllSBP routine for more.
  1074.  
  1075.      The default volume is set to 16. Minimum is 0, maximum is 127. For a linear
  1076.      approximation of this volume control, 16 is about half-volume, 8 about 1/4,
  1077.      64 about 3/4, and 127 full volume. A volume other than 16 may
  1078.      cause a slowdown in performance so 16 should be used as much as possible.
  1079.  
  1080.      Note: SETTING THE VOLUME TO 0 TURNS OFF THE SOUND BLASTER AND PRO'S
  1081.            SPEAKER (REQUIRED BEFORE RECORDING). ANY OTHER SETTING TURNS
  1082.            THE SPEAKER CONNECTION ON.
  1083.  
  1084.      The interrupt rate sets the playback rate of background play for non-DMA
  1085.      mode. For example, let's say you load a file that was recorded with a
  1086.      sample rate of 8000Hz (this information is stored with the VOC or WAVE).
  1087.      That is the value to which you set the interrupt rate. Easy enough. But
  1088.      let's say that it was recorded at 44,100Hz and in stereo. Normally, this
  1089.      data file couldn't be played except with high-end sound cards. What you can
  1090.      do is set the interrupt rate to 8000Hz and have RUCKUS-DAC perform on-the-
  1091.      fly downsampling so that you can play this file on any of the supported
  1092.      devices (in non-DMA mode).
  1093.  
  1094.      In addition to downsampling, RUCKUS-DAC can upsample with the PC Speaker
  1095.      and AdLib cards (the two that need it the most). Let's take that 8000Hz
  1096.      sample rate file again. Upsampling performs on-the-fly adjustments to the
  1097.      data so that it sounds as if the file sample rate were twice the original.
  1098.      This results in a much cleaner sound. There is a drawback: much more CPU
  1099.      time is needed at this high rate, and it should only be used on powerful
  1100.      CPUs. To use the upsampling capabilities of RUCKUS-DAC, set the interrupt
  1101.      rate to the original sample rate. There is also a special method used in
  1102.      the initialization of the device. See InitDac for more. You can experiment
  1103.      with the down- and upsampling of RUCKUS-DAC by using the MODAC.EXE program.
  1104.  
  1105.      When using non-DMA mode, you can select from three priority levels. The
  1106.      default priority=1. This level allows the system to run as normal, even
  1107.      though the computer's ticker has been sped up some thousand times. Priority
  1108.      level 2 hogs all background time for the RUCKUS-DAC playback. The
  1109.      computer's clock is not updated. Priority level 0 gives top priority to
  1110.      other computer events. This level may result in a warbly sound. Priority
  1111.      only affects non-DMA VOC/WAVE output. Use the default level (1).
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.                                                                               17
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.      The default interrupt rate is 10989. If you are on a slow machine, this may
  1130.      be too high for non-DMA operations. The following table shows the min, max,
  1131.      and nominal interrupt rate for the supported devices. In all cases, higher
  1132.      rates require more CPU power, except in DMA mode. Nominal values based on a
  1133.      386/25 CPU.
  1134.  
  1135.        Device   MinRate   MaxRate  Nominal  Comments
  1136.        ------   -------   -------  -------  ------------------------------------
  1137.        PCSKP0      5000     18000     8000  rates < 16000 may be noisy
  1138.        PCSPK1      5000      9000     8000  effective rate=rate*2
  1139.        LPTDAC      5000     23000    15000  not tested
  1140.        DISNEY      5000      7000     7000  max usable rate is 7000Hz
  1141.        ADLIB0      5000     12000     8000  AdLib very slow as digital device
  1142.        ADLIB1      5000      6000     5500  effective rate=rate*2
  1143.        SB          5000     23000    15000  DMA mode is 5-23000, record to 12kHz
  1144.        SB PRO      5000     23000    15000  DMA mode is 5-45500
  1145.  
  1146.      Sample Use:
  1147.  
  1148.      struct SetPack SP;
  1149.  
  1150.      SP.Func = SetAllDac;
  1151.      SP.Volume = 16;       // any other value slows down performance
  1152.      SP.IntRate = 8000;      
  1153.      SP.Priority = 1;
  1154.      rez = RUCKDAC(&SP);
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.                                                                               18
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.      SetVolumeDac        Func: 21       Pack: SetPack
  1196.  
  1197.      SetVolumeDac does two things. First, it controls the non-DMA mode output
  1198.      volume. Second, it turns the SB's speaker on and off; the SB speaker must
  1199.      be off, and remain off, while recording. Under normal use, the SB speaker
  1200.      is turned on and off by RUCKUS automatically.
  1201.  
  1202.      Because of the extra calculations required when the volume is set to
  1203.      anything other than the default (16), it's recommended that the volume be
  1204.      changed only when necessary (especially on slow machines).
  1205.  
  1206.      This routine controls the output volume on all devices in non-DMA mode. In
  1207.      DMA-mode, the SB's volume is not controllable. The SB PRO, however, has a
  1208.      large set of mixer controls that can be controlled via RUCKUS-DAC. See
  1209.      SetAllSBP for more.
  1210.  
  1211.      Sample Use:
  1212.  
  1213.      struct SetPack SP;
  1214.  
  1215.      SP.Func = SetVolumeDac;
  1216.      SP.Volume = 127;          // set to max volume
  1217.      rez = RUCKDAC(&SP);
  1218.      if (rez != 0)
  1219.         // you probably didn't set SP.Func correctly
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.                                                                               19
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.      SetIntRateDac       Func: 22       Pack: SetPack
  1262.  
  1263.      SetIntRateDac, with respect to the -DAC section of RUCKUS, controls the
  1264.      playback rate of non-DMA output.
  1265.  
  1266.      After loading a file, that file's sample rate is available in the DAC data
  1267.      section. You may choose to have the digital data file played back at that
  1268.      rate, or, you may choose to downsample the original rate. Downsampling is
  1269.      useful since it allows slower computers to play data files originally
  1270.      sampled at rates too high to be played back -- RUCKUS can play a 44.1kHz
  1271.      stereo VOC or WAVE file back through the PC speaker, or any of the other
  1272.      supported devices. Note that the actual downsampled rate is not always
  1273.      exactly what you specify, but a best-fit approximation.
  1274.  
  1275.      As an example, let's suppose you have a VOC file originally sampled at
  1276.      22050Hz, mono format. While this can easily be played on the SBs using DMA-
  1277.      mode playback, non-DMA mode requires a very powerful CPU to handle that
  1278.      high a rate. After loading using LoadDac, the 22050 sample rate, and its
  1279.      mono format, is determined by reading the DAC data section. To play back
  1280.      this file through PCSPKR0, say, at 11kHz, you'd set SP.IntRate=11025.
  1281.  
  1282.      With the PC speaker and the AdLib, there are two different output modes.
  1283.      The first either plays at the original rate, or is downsampled to a lower
  1284.      rate (as specified by you). The second mode upsamples. By upsampling,
  1285.      RUCKUS can output a much cleaner sound than playing at the original sample
  1286.      rate. However, this is useful only for samples that were originally at a
  1287.      low sample rate. You would not want to upsample a VOC file that was sampled
  1288.      at 22kHz, since that would demand too much CPU power, plus, very little
  1289.      benefit would be achieved. The best use of upsampling is on data that was
  1290.      originally sampled at, say, 8kHz or less. In order to properly upsample,
  1291.      you need to specify a SP.IntRate equal to the original sample rate (this
  1292.      can be found in the DAC data section immediately after a LoadDac).
  1293.  
  1294.      As mentioned, upsample mode is available on the speaker and AdLib devices
  1295.      only. To specify this mode, set the IP.IOport to the physical port when
  1296.      initializing the device (InitDac). In the PC speaker's case, IP.IOport=0x42
  1297.      would activate up-sample mode. Using IP.IOport=0 would have the regular
  1298.      mode used. For the AdLib, specify IP.IOport=0x388. As with the PC speaker,
  1299.      setting IP.IOport=0 uses the regular AdLib play mode.
  1300.  
  1301.      Sample Use:
  1302.  
  1303.      struct SetPack SP;
  1304.  
  1305.      SP.Func = SetIntRateDac;
  1306.      SP.IntRate = 11025;
  1307.      rez = RUCKDAC(&SP);
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.                                                                               20
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.      SetPriorityDac      Func: 23       Pack: SetPack
  1328.  
  1329.      When operating in non-DMA mode playback of VOC or WAVE data, RUCKUS
  1330.      reprograms the system timer. Normally, this timer runs at the familiar 18.2
  1331.      times per second rate. When you play back at, say, a SP.IntRate=10000, this
  1332.      is the new rate that the system timer is set to operate at. So, instead of
  1333.      the timer interrupting the CPU (via IRQ0) 18.2/sec, it interrupts at
  1334.      10,000/sec. 
  1335.  
  1336.      The routine allows you to control the priority given to other events while
  1337.      the timer is operating at this accelerated pace. The default priority is 1.
  1338.      At the priority, the playback code is called at the desired rate, and,
  1339.      given a 10kHz rate, every 550th time the playback code is executed, the
  1340.      original timer-dependant code is executed. This allows the system clock,
  1341.      and any other system in the computer dependant on the clock, to be properly
  1342.      maintained. On each 550th call, RUCKUS first performs all tasks that needs
  1343.      to be done, then it calls the original system code. In most cases, if not
  1344.      all, this priority works best.
  1345.  
  1346.      Priority 0 is exactly like priority 1 except that control is released as
  1347.      soon as the RUCKUS code starts. The permits other tasks to interrupt
  1348.      RUCKUS. This may cause a warbly-type sound, but permits, say, high-speed
  1349.      communications code to operate in the background with missing a beat.
  1350.  
  1351.      Priority 2 causes RUCKUS to use (hog) all background processing time for
  1352.      itself. The system clock is not maintained. Use this priority only if the
  1353.      other two are causing problems (doubtful) or if you want to get the maximum
  1354.      sound performance out of RUCKUS and don't care if the system clock is
  1355.      maintained.
  1356.  
  1357.  
  1358.      Sample Use:
  1359.  
  1360.      struct SetPack SP;
  1361.  
  1362.      SP.Func = SetPriorityDac;
  1363.      SP.Priority = 1;   // 1 is the default so no need to call unless changed
  1364.      rez = RUCKDAC(&SP);
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.                                                                               21
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.      GetBufferDataDac    Func: 28       Pack: GetDataPack
  1394.  
  1395.      Used to get a specified number of bytes from the current digital data path.
  1396.  
  1397.      This routine is currently under development and should not be used.
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.                                                                               22
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.      GetBytePosDac       Func: 29       Pack: GetDataPack
  1460.  
  1461.      Used to determine where in the current digital data path processing is
  1462.      occurring.
  1463.  
  1464.      Sample Use:
  1465.  
  1466.      struct GetDataPack GDP;
  1467.  
  1468.      GDP.Func = GetBytePosDac;
  1469.      rez = RUCKDAC(&GDP);
  1470.      if (rez == 0)
  1471.         printf("Curr pos relative start of data is %ul", GDP.BytePos);
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.                                                                               23
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.      SetAllSBP           Func: 30       Pack: SetProPack
  1526.  
  1527.      This routine allows you to control the mixer facility of the Sound Blaster
  1528.      Pro including main volume, VOC volume, mic level, CD level, line level,
  1529.      output filter, input source selection, record filters, input source, and
  1530.      stereo/mono record mode.
  1531.  
  1532.      During initialization of the Sound Blaster Pro (InitDac), the main and VOC
  1533.      volumes are set to maximum (15) for both left and right channels, the three
  1534.      input levels are set to their minimums (1), all filters are set to off,
  1535.      mode is set to mono record, and input selection is set to mic.
  1536.  
  1537.      NOTE: PLAYBACK OF VOC AND WAVE STEREO DATA FILES IS AUTOMATIC. THE STEREO
  1538.            MODE SETTING IS FOR RECORDING ONLY. TO PLAY STEREO FILES IN MONO
  1539.            ON THE SB PRO, USE THE SOUND BLASTER (DEVICE 4) INSTEAD.
  1540.  
  1541.      The main volume (left and right, as are all mixer controls except mic)
  1542.      adjusts both the digital and synthesizer outputs of the PRO (the
  1543.      synthesizer, or FM section, is not used by RUCKUS-DAC, but is in RUCKUS-
  1544.      MIDI). In normal use the main volume channels would be set to 15, the
  1545.      maximum.
  1546.  
  1547.      The VOC volume adjusts the volume of the digital output channels. Anything
  1548.      played through the SB PRO's digital channels can be adjusted with this. As
  1549.      with the main volume, the VOC volume is normally set to 15, the maximum.
  1550.  
  1551.      The SB PRO provides for three inputs. Mic, CD, and Line. Each of these have
  1552.      separate level adjustments. The mic input level is the odd one out. Unlike
  1553.      the other two, the mic level does not adjust the mic input level, but
  1554.      rather the mic output level. Whenever you record via the mic input line at
  1555.      the back of the card, the input level is controlled by an AGC, automatic
  1556.      gain control. The AGC acts as a real-time level adjuster -- high signal
  1557.      levels (loud sounds) have the AGC automatically decrease the mic input
  1558.      sensitivity -- low signal levels (quiet sounds) have it automatically
  1559.      increase the mic input sensitivity. The actions of an AGC has its drawbacks
  1560.      in reduced dynamic range and perhaps a noticeable "breathing" of the sound
  1561.      on playback. Breathing is where the background noise increases as the level
  1562.      of the sound decreases. However, often the reduced dynamic range makes for
  1563.      a better final results, especially when using a mic/SB combination.
  1564.  
  1565.      The CD input level adjusts the level of the CD-ROM device. No testing has
  1566.      been done with this. It controls the input level from the proprietary CD-
  1567.      ROM drive that CLabs distributes for the SB PRO, or one which is compatible
  1568.      (and is hooked up to the SB PRO's CD connector). Any CD should be able to
  1569.      plug into the CD audio connector of the SB PRO (see the SB PRO docs) and so
  1570.      have its level controllable via RUCKUS-DAC.
  1571.  
  1572.      The Line input level adjusts the input sensitivity. Normally, when
  1573.      recording from this input, the Line level should be set to 15, the maximum.
  1574.      For preamps that have an unusually high line out level, reducing the PRO's
  1575.      line input level may produce a better recording.
  1576.  
  1577.      The output filter can be used to reduce the noise at the mid and high end
  1578.      of the digital data being played. Normally, this filter is not needed.
  1579.  
  1580.                                                                               24
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.      The recording filters are very useful and should be used whenever the
  1593.      recording sample rate is below 18kHz and the source being record has
  1594.      frequencies above 9kHz. There are two filters to choose from: one has a
  1595.      3.2kHz cutoff, the other 8.8kHz.
  1596.  
  1597.      Whenever you are recording from a source that will include frequencies
  1598.      higher than 3.2kHz, and you have the PRO recording at a sample rate under
  1599.      6.4kHz, you should select the 3.2kHz filter. This will attenuate
  1600.      frequencies higher than 3.2kHz and should help produce a cleaner recording.
  1601.      Along the same lines, if you are recording frequencies higher than 8.8kHz,
  1602.      and are recording using a sample rate less than 17.6kHz, you should use the
  1603.      8.8kHz filter. Note that filter use as described above is not a rule, just
  1604.      a guideline. You may find that using no filters is best.
  1605.  
  1606.      With the SB PRO you have 3 input sources to record from: the mic, a CD-ROM
  1607.      drive attached to the SB PRO (requires special cable), or a line-level
  1608.      input. The mic allows mono recording only. The CD-ROM facility controls
  1609.      only a CD-ROM drive hooked up to the SB PRO. The line input can be
  1610.      connected directly to a preamplifier's line out jacks.
  1611.  
  1612.      The SB PRO allows you to record in STEREO from the CD and LINE input
  1613.      sources; mic is always mono. When recording in stereo, the sample rate you
  1614.      record at must be set to twice the desired rate. For example, if you want
  1615.      to record from the LINE input at 22.05kHz, in stereo, set the recording
  1616.      rate to twice 22,050, or 44,100. The SB PRO can sample up to a 45,500Hz
  1617.      rate (which, if a stereo recording, is an effective rate of 22,750Hz). See
  1618.      RecordDac for more.
  1619.  
  1620.      Sample Use:
  1621.  
  1622.      struct SetProPack SPP;  // be careful not to type SBP
  1623.  
  1624.      SPP.Func = SetAllSBP;
  1625.      SPP.Volume = 0x0F0F;    // max out volumes
  1626.      SPP.VolVoc = 0x0F0F;
  1627.  
  1628.      SPP.VolMic = 0;         // minimized mic input level
  1629.      SPP.CD = 0;             // actual min for SB Pro is 1
  1630.      SPP.LI = 0;
  1631.  
  1632.      SPP.FilterOut = 0;      // 0=off filter, 1=on (output filter)
  1633.      SPP.FilterIn = 0;       // 0=off filter, 1=3.2kHz, 2=8.8kHz (record filter)
  1634.      SPP.SourceIn = 0;       // 0=mic, 1=CD, 2=line
  1635.      SPP.StereoIn = 0;       // record mode: 0=mono, 1=stereo
  1636.      rez = RUCKDAC(&SPP);
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.                                                                               25
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.      SetVolMainSBP       Func: 31       Pack: SetProPack
  1658.  
  1659.      The main volume (left and right) adjusts both the digital and synthesizer
  1660.      outputs of the PRO; it is the overall volume setting. Each of these outputs
  1661.      also has its own volume control. In normal use, the main volume channels
  1662.      would be set to 15, the maximum.
  1663.  
  1664.      The range of volume is 1 to 15, in steps of 2 (1,3,5,7,9,11,13,15). To set
  1665.      the left channel main volume, multiply the volume desired by 256. To set
  1666.      the right channel, just add its value. For example, to set the main volume
  1667.      to maximum (15, or 0F hex), multiply 15*256 and add 15. In hex, this value
  1668.      is 0F0F (decimal 3855, but decimal is much too awkward). If you know
  1669.      beforehand that you want the main volume at maximum, you can forego the
  1670.      multiplication and simply use 0F0F, as in the example below.
  1671.  
  1672.      NOTE: Since you are the programmer and you have the documentation, do not
  1673.            depend on RUCKUS correcting out-of-value parameters. If you use 
  1674.            parameters that are not within specifications, the results are
  1675.            undefined.
  1676.  
  1677.      Sample Use:
  1678.  
  1679.      struct SetProPack SPP;
  1680.  
  1681.      SPP.Func = SetVolMainSBP;
  1682.      SPP.Volume = 0x0F0F;
  1683.      rez = RUCKDAC(&SPP);
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.                                                                               26
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.      SetVolVocSBP        Func: 32       Pack: SetProPack
  1724.  
  1725.      The VOC volume (left and right) adjusts the digital output volume of the
  1726.      PRO. The range of volume is 1 to 15, in steps of 2 (1,3,5,7,9,11,13,15). To
  1727.      set the left channel VOC volume, multiply the volume desired by 256. To set
  1728.      the right channel, just add its value. For example, to set the VOC volume
  1729.      to maximum (15, or 0F hex), multiply 15*256 and add 15. In hex, this value
  1730.      is 0F0F (decimal 3855, but decimal is much too awkward). If you know
  1731.      beforehand that you want the VOC volume at maximum, you can forego the
  1732.      multiplication and simply use 0F0F, as in the example below.
  1733.  
  1734.      Sample Use:
  1735.  
  1736.      struct SetProPack SPP;
  1737.  
  1738.      SPP.Func = SetVolMainSBP;
  1739.      SPP.VolVoc = 0x0F0F;
  1740.      rez = RUCKDAC(&SPP);
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.                                                                               27
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.      SetLevelMicSBP      Func: 33       Pack: SetProPack
  1790.  
  1791.      This routine does not actually adjust the mic input level, but rather the
  1792.      mic output level. Whenever you record via the mic input line at the back of
  1793.      the card, the input level is controlled by an AGC, automatic gain control.
  1794.      The AGC acts as a real-time level adjuster -- high signal levels (loud
  1795.      sounds) have the AGC automatically decrease the mic input sensitivity --
  1796.      low signal levels (quiet sounds) have it automatically increase the mic
  1797.      input sensitivity. The actions of an AGC has its drawbacks in reduced
  1798.      dynamic range and perhaps a noticeable "breathing" of the sound on
  1799.      playback. Breathing is where the background noise increases as the level of
  1800.      the sound decreases. However, often the reduced dynamic range makes for a
  1801.      better final results, especially when using a mic/SB combination.
  1802.  
  1803.      By setting the mic input level, you can use the computer as a public
  1804.      address system. To do this, select mic as the input source, set the mic
  1805.      input level to maximum, and turn on the SB speaker. To avoid feedback, keep
  1806.      the mic away from the loudspeakers.
  1807.  
  1808.      The input level range is 1 to 7, in steps of 2 (1,3,5,7). This setting has
  1809.      no effect on recording level (see above).
  1810.  
  1811.      Sample Use:
  1812.  
  1813.      struct SetProPack SPP;
  1814.  
  1815.      SPP.Func = SetVolMicSBP;
  1816.      SPP.VolVoc = 0x07;
  1817.      rez = RUCKDAC(&SPP);
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.                                                                               28
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.      SetLevelCDSBP       Func: 34       Pack: SetProPack
  1856.  
  1857.      The CD input level (left and right) adjusts the input level of the attached
  1858.      CD-ROM drive. This has not been tested. For its use, see SetLevelLineSBP.
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864.  
  1865.  
  1866.  
  1867.  
  1868.  
  1869.  
  1870.  
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.                                                                               29
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.      SetLevelLineSBP     Func: 35       Pack: SetProPack
  1922.  
  1923.      The line level (left and right) adjusts the analog input level of the PRO.
  1924.      The range of volume is 1 to 15, in steps of 2 (1,3,5,7,9,11,13,15). To set
  1925.      the left channel line level, multiply the volume desired by 256. To set the
  1926.      right channel, just add its value. For example, to set the line level to
  1927.      maximum sensitivity (15, or 0F hex), multiply 15*256 and add 15. In hex,
  1928.      this value is 0F0F (decimal 3855, but decimal is much too awkward). If you
  1929.      know beforehand that you want the line level at maximum, you can forego the
  1930.      multiplication and simply use 0F0F, as in the example below.
  1931.  
  1932.      Sample Use:
  1933.  
  1934.      struct SetProPack SPP;
  1935.  
  1936.      SPP.Func = SetVolMainSBP;
  1937.      SPP.VolLI = 0x0F0F;
  1938.      stat = RUCKDAC(&SPP);
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.                                                                               30
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.      SetFilterOutSBP     Func: 36       Pack: SetProPack
  1988.  
  1989.      The output filter of the PRO can be used to reduce the noise at the mid and
  1990.      high end of the digital data being played. Normally, this filter is not
  1991.      needed. Recordings made at a very low sample rate, say, under 6kHz, may
  1992.      sound better with this output filter on.
  1993.  
  1994.      The digital output filter, and also the analog recording filter, is set off
  1995.      by default. 
  1996.  
  1997.      Sample Use:
  1998.  
  1999.      struct SetProPack SPP;
  2000.  
  2001.      SPP.Func = SetFilterOutSBP;
  2002.      SPP.FilterOut = 1;          // enable output filter
  2003.      rez = RUCKDAC(&SPP);
  2004.  
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.                                                                               31
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.      SetFilterInSBP      Func: 37       Pack: SetProPack
  2054.  
  2055.      The recording filters are very useful and should be used whenever the
  2056.      recording sample rate is below 18kHz and the source being record has
  2057.      frequencies above 9kHz. There are two filters to choose from: one has a
  2058.      3.2kHz cutoff, the other 8.8kHz.
  2059.  
  2060.      Whenever you are recording from a source that will include frequencies
  2061.      higher than 3.2kHz, and you have the PRO recording at a sample rate under
  2062.      6.4kHz, you should select the 3.2kHz filter. This will attenuate
  2063.      frequencies higher than 3.2kHz and should help produce a cleaner recording.
  2064.      Along the same lines, if you are recording frequencies higher than 8.8kHz,
  2065.      and are recording using a sample rate less than 17.6kHz, you should use the
  2066.      8.8kHz filter. Note that filter use as described above is not a rule, just
  2067.      a guideline. You may find that using no filters is best.
  2068.  
  2069.      The input filter is off by default.
  2070.  
  2071.      Sample Use:
  2072.  
  2073.      struct SetProPack SPP;
  2074.  
  2075.      SPP.Func = SetFilterInSBP;
  2076.      SPP.FilterIn = 1;       // 0=no filter, 1=3.2kHz cutoff, 2=8.8kHz cutoff
  2077.      rez = RUCKDAC(&SPP);
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.                                                                               32
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.      SetSourceSBP        Func: 38       Pack: SetProPack
  2120.  
  2121.      With the SB PRO you have three input sources to record from: the mic, a CD-
  2122.      ROM drive attached to the SB PRO (requires special cable), or a line-level
  2123.      input. The mic allows mono recording only. The CD-ROM facility controls
  2124.      only a CD-ROM drive hooked up to the SB PRO. The line input can be
  2125.      connected directly to a preamplifier's line out jacks.
  2126.  
  2127.      Recording with the mic requires only that it be selected. The mic input
  2128.      level does not control the recording level, but rather the PA output. See
  2129.      SetAllSBP for more.
  2130.  
  2131.      Recording from the connected CD-ROM drive has not been tested. If you can
  2132.      control the CD, you can record from it using RUCKUS.
  2133.  
  2134.      Recording from the line-level input is simple. Just hook your tape-out
  2135.      jacks from your preamplifier to the cable supplied with the SB PRO. This
  2136.      cable, a 1/8-inch mini stereo to 2 RCA phono jacks is the same one that
  2137.      comes with the original Sound Blaster. You'll probably need more cable
  2138.      unless you have your preamp nearby. 
  2139.  
  2140.      When recording from either the CD or line, you must set the source's input
  2141.      level. Normally, setting it to maximum (15) is best. If you have
  2142.      particularly high line output levels, you may need to set this lower. As
  2143.      with all mixer settings, settings are 1 to 15 in steps of 2. The mic is 1
  2144.      to 7, by 2.
  2145.  
  2146.      Sample Use:
  2147.  
  2148.      struct SetProPack SPP;
  2149.  
  2150.      SPP.Func = SetSourceSBP;
  2151.      SPP.SourceIn = 2;         // set input source to line input
  2152.      rez = RUCKDAC(&SPP);
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.                                                                               33
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.      SetStereoSBP        Func: 39       Pack: SetProPack
  2186.  
  2187.      The SB PRO allows you to record in STEREO from the CD and LINE input
  2188.      sources; mic is always mono. When recording in stereo, the sample rate you
  2189.      record at must be set to twice the desired rate. For example, if you want
  2190.      to record from the LINE input at 22.05kHz, in stereo, set the recording
  2191.      rate to twice 22,050, or 44,100. The SB PRO can sample up to a 45,500Hz
  2192.      rate (which, if a stereo recording, is an effective rate of 22,750Hz). See
  2193.      RecordDac for more.
  2194.  
  2195.      You must set the mode to stereo or mono before starting the actual record.
  2196.  
  2197.      Sample Use:
  2198.  
  2199.      struct SetProPack SPP;
  2200.  
  2201.      SPP.Func = SetStereoSBP;
  2202.      SPP.StereoIn = 1;         // set to stereo record
  2203.      rez = RUCKDAC(&SPP);
  2204.  
  2205.  
  2206.  
  2207.  
  2208.  
  2209.  
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.                                                                               34
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.      SetSpeakerSB        Func: 40       Pack: SetPack
  2252.  
  2253.      The routine activates or deactivates the Sound Blasters' output. When
  2254.      recording it must be off. When playing back, it must be on. When starting a
  2255.      recording, RUCKUS automatically turns the speaker off; when playing back it
  2256.      turns the speaker on. For those occasions when you want to control the
  2257.      speaker connection, use this routine.
  2258.  
  2259.      Note that the generic SetVolumeDac also controls the SB's speaker
  2260.      connection. If the speaker is currently on and you set the volume to 0, the
  2261.      SB speaker is turned off. And, of the speaker is currently off, and you set
  2262.      the volume to a non-zero value, the speaker is turned on. This routine lets
  2263.      you control the connection without changing the generic volume setting.
  2264.  
  2265.      Sample Use:
  2266.  
  2267.      struct SetPack SP;
  2268.  
  2269.      SP.Func = SetSpeakerSB;
  2270.      SP.Volume = 0;           // use the volume member of SP to control speaker
  2271.      rez = RUCKDAC(&SP);      // to turn the speaker on, set SP.Volume = 1
  2272.                               // THIS DOES NOT ALTER THE VOLUME
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.                                                                               35
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.      GetMixerRegSBP      Func: 48       Pack: GetDataPack
  2318.  
  2319.      Get a SB PRO mixer port-value.
  2320.  
  2321.      This routine is under development and should not be used.
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.                                                                               36
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.      GetDacSB            Func: 49       Pack: GetDataPack
  2384.  
  2385.      This routine gets a byte from the Sound Blasters data channel. This routine
  2386.      should not be called while the Sound Blaster is playing or record. It can
  2387.      be used for level tests.
  2388.  
  2389.      Before using this routine on the PRO, first select the input device (mic,
  2390.      CD, or line) and then perform a 64-byte record from that device. This
  2391.      because the input device is not selected until you actually record from it.
  2392.  
  2393.      Unlike the other RUCKDAC routines, the return value is not the error code,
  2394.      but rather the data byte itself. To check for an error, use GDP.stat (as
  2395.      you can in all RUCKUS functions).
  2396.  
  2397.      Sample Use:
  2398.  
  2399.      struct GetDataPack GDP;
  2400.  
  2401.      GDP.Func = GetDacSB;
  2402.      data = RUCKDAC(&GDP);
  2403.      if (GDP.stat != 0) 
  2404.        // error 
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.                                                                               37
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.      ExitMod             Func: 50       Pack: XitPack
  2450.  
  2451.      When using RUCKUS, certain aspects of the computer are controlled by the
  2452.      RUCKUS code. To have RUCKUS return full control back to the computer and
  2453.      operating system, ExitMod must be called. To ensure that this happens, even
  2454.      after an abnormal termination (such as an untrapped divide by zero), RUCKUS
  2455.      also provides a routine that ensures that ExitMod is always called before
  2456.      your application ends and returns to the operating system. See AtExitMod
  2457.      for more.
  2458.  
  2459.      Once you have loaded a mod file via LoadMod, or performed any mod function,
  2460.      you must call ExitMod before you end you program and return to DOS. Calling
  2461.      ExitMod releases any memory allocations made, and also performs other
  2462.      system cleanup.
  2463.  
  2464.      Sample Use:
  2465.  
  2466.      struct XitPack XP;
  2467.  
  2468.      XP.Func = ExitMod;
  2469.      rez = RUCKDAC(&XP);
  2470.  
  2471.  
  2472.  
  2473.  
  2474.  
  2475.  
  2476.  
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.                                                                               38
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.      AtExitMod           Func: 51       Pack: XitPack
  2516.  
  2517.      To ensure that all machine control is returned to the operating system and
  2518.      that all RUCKUS-made memory allocations are released, before your
  2519.      application program ends, AtExitMod should be used (if you have used the
  2520.      mod extensions to RUCKUS-DAC). This routine takes advantage of most
  2521.      compiler's _atexit enregistration routine. This _atexit compiler run-time
  2522.      library routine allows for up to 32 different calls to be made just prior
  2523.      to it (the compiler's run-time code) returning to the operating system
  2524.      (program termination). Most of the time, you can make all the necessary
  2525.      shutdowns that your program requires in your app's code. However, abnormal
  2526.      terminations--terminations that can cause a bypass of your own shutdown
  2527.      code, may mean that when the operating systems regains control, certain
  2528.      machine operations are not in a stable state. The AtExitMod routine ensures
  2529.      that ExitMod is called no matter what (in most all cases, except where the
  2530.      program locks up, in which case the session needs to be reset anyway). 
  2531.  
  2532.      Graphically, your program executes like this:
  2533.  
  2534.         DOS C>program.exe
  2535.           |
  2536.         Compiler startup code (performs basic setup)
  2537.           |
  2538.           +----->+
  2539.                  | Your program starts, ends
  2540.           +<-----+
  2541.           |   
  2542.          rest of startup code, _atexit registered routines
  2543.           |
  2544.          DOS C>_
  2545.  
  2546.      Caution: In order for the _atexit registered routines to be called by your
  2547.      compilers run-time, you must not allow you program to exit via non-standard
  2548.      ways. Calling INT21/4C is on example (you should never do this from
  2549.      compiled code, anyway).
  2550.  
  2551.      The startup code is basically a program that sets up your program to run,
  2552.      calls your program, regains control when your program ends, then performs
  2553.      the necessary shutdown actions required, including calling all routines
  2554.      registered with _atexit. See AtExitDac for an important addition.
  2555.  
  2556.      Sample Use:
  2557.  
  2558.      struct XitPack XP;
  2559.  
  2560.      XP.Func = AtExitMod;
  2561.      rez = RUCKDAC(&XP);
  2562.      if (rez != 0)
  2563.         puts("_atexit is full (more than 32 calls made to _atexit)");
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.                                                                               39
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.      LoadMod             Func: 52       Pack: LoadPack
  2582.  
  2583.      It is required that RUCKUS load mod files into memory. RUCKUS makes the
  2584.      necessary memory allocations and loads the data into conventional memory,
  2585.      with UMB blocks used if available and controlled by DOS (via DOS=,UMB in
  2586.      CONFIG.SYS). Only one mod file may be in memory at any one time. To unload
  2587.      the mod file you must execute an ExitMod call.
  2588.  
  2589.      LoadMod can be instructed to start loading at any particular byte in a
  2590.      file. This would be useful, for example, if you have a single file made up
  2591.      of several mod files, appended to form one large data file.
  2592.  
  2593.      Sample Use:
  2594.  
  2595.      struct LoadPack LP;
  2596.  
  2597.      LP.Func = LoadMod;
  2598.      LP.FilenamePtr = filename;
  2599.      LP.StartPos = 0L;  // start load at first byte of file
  2600.      LP.LoadSize = 0L;  // have RUCKUS load all of it
  2601.      LP.XMMflag = 0;    // this must be set to zero
  2602.      rez = RUCKDAC(&LP);
  2603.  
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.                                                                               40
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.      PlayMod             Func: 53       Pack: PlayBackPack
  2648.  
  2649.      Once the mod file has been loaded, you can play it to any of the RUCKUS-
  2650.      supported devices. There are 4 modes that can be used for playback; non-DMA
  2651.      foreground, non-DMA background, DMA foreground, and DMA background. The DMA
  2652.      modes require the Sound Blasters. Also, for STEREO mod playback, DMA mode
  2653.      is required (SB Pro only).
  2654.  
  2655.      Playing in the background allows your computer program to regain control
  2656.      immediately after play has begun. If you choose foreground play, control
  2657.      does not return to your program until the end of the data has been played,
  2658.      or, until CTRL-ALT is pressed. In all cases, mod file playback is best done
  2659.      on a fast computer, though excellent results can be gotten from 286-class
  2660.      machines. For slow machines, DMA foreground allows for best sound, since
  2661.      you can set the mod process rate higher than you can if you choose a
  2662.      background mode.  
  2663.  
  2664.      Before play, you should set up other parameters by calling the other Set
  2665.      mod routines (SetIntRateMod, SetStereoMod, and SetFastMod).
  2666.  
  2667.      NOTE: SOME MACHINES ARE NOT ABLE TO HANDLE BACKGROUND DMA MODE AT HIGH 
  2668.            RATES, EVEN ON 486-CLASS MACHINES. HOWEVER, BOTH MY 486/33 AND
  2669.            MY 286/16 WORK WELL IN THIS MODE. THE 486/33 CAN PROCESS MOD DATA
  2670.            AT RATES UP TO THE PRO'S MAX, 45,500Hz. THE 286/16 CAN PROCESS UP 
  2671.            TO 16kHz IN THIS MODE AND 22kHz IN DMA FOREGROUND. A 286/6 HAS 
  2672.            BEEN TESTED TO 8kHz (DMA FOREGROUND) AND PERFORMS WELL. A 12MHz
  2673.            DID 16kHz. ON SLOWER MACHINES, USING A LARGER DMA BUFFER SIZE
  2674.            AND A HIGHER DMAX: VALUE ALLOWS FOR HIGHER RATES TO BE ACHIEVED.
  2675.            IT IS POSSIBLE TO LOCK UP A MACHINE IF TOO HIGH A RATE IS ATTEMPTED.
  2676.  
  2677.      struct PlaybackPack PBP;
  2678.  
  2679.      PBP.Func = PlayMod;
  2680.      PBP.Mode = 3;      // mode 0=foreground, 1=background, 2=DMA FG, 3=DMA BG
  2681.      PBP.XMMhandle = 0; // this must be set to 0
  2682.  
  2683.      // PBP.LoadPtr is not used by PlayMod
  2684.  
  2685.      PBP.BufferSize = 4096;// buffer size is bytes per buffer (2 buffers used)
  2686.                            // minimum size is 2048, maximum is 65520
  2687.                            // buffers allocated only if DMA play (mode=2 or 3)
  2688.      rez = RUCKDAC(&PBP);
  2689.      if (rez == 0)
  2690.         // if background mode then the mod data is playing now, but
  2691.         // if foreground mode, the play has ended by the time we get here
  2692.      else
  2693.         // play error (could be not enough memory for PBP.BufferSize)
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.                                                                               41
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.      EndMod              Func: 54       Pack: XitPack
  2714.  
  2715.      EndMod is used to end (stop) play on command. Once PlayMod has started, it
  2716.      continues to play in the background until either the end of the mod data
  2717.      has been reached, or you call this routine.
  2718.  
  2719.      Sample Use:
  2720.  
  2721.      struct XitPack XP;
  2722.  
  2723.      // LoadMod and PlayMod have already been called
  2724.      // see those routines for more information
  2725.  
  2726.      XP.Func = EndMod;     // if play is active this call
  2727.      rez = RUCKDAC(&XP);   // ends it
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.                                                                               42
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.      PauseMod            Func: 55       Pack: PausePack
  2780.  
  2781.      PauseMod allows you to temporarily pause and then restart a playback.
  2782.  
  2783.      Sample Use:
  2784.  
  2785.      struct PausePack PP;
  2786.  
  2787.      PP.Func = PauseMod;
  2788.      PP.Pause = 1;        // non-zero pauses, zero restarts
  2789.      rez = RUCKDAC(&PP);
  2790.  
  2791.  
  2792.  
  2793.  
  2794.  
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800.  
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.  
  2812.  
  2813.  
  2814.  
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.                                                                               43
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.      SetIntRateMod       Func: 56       Pack: SetModPack
  2846.  
  2847.      SetIntRateMod, with respect to the mod extensions of RUCKUS, controls the
  2848.      mod data processing rate, which in turn, is the playback rate (the opposite
  2849.      of sample rate).
  2850.  
  2851.      A process rate of 22kHz should be considered a practical maximum. Higher
  2852.      process rates are possible (up to 45.5kHz with the PRO) but the improvement
  2853.      in sound quality over 22kHz is negligible (to me). If the machine is
  2854.      capable, a rate of at least 16kHz should be used. At this rate, sound is
  2855.      reasonably good sounding. Rates below 16kHz will most likely incur a high-
  2856.      pitched whistling noise that can be very annoying. Using the output filter
  2857.      of the SB PRO helps. The whistle is totally absent from the output of the
  2858.      Disney Sound Source (which internally plays at 7kHz regardless of the input
  2859.      stream rate). For PC speaker output, rates above 18kHz are not recommended.
  2860.      Best performance for the PC speaker is at 16kHz. The AdLib, being a very
  2861.      slow device when made to play digital data, has an effective top-end of
  2862.      about 13kHz. 
  2863.  
  2864.      When using the SB PRO in stereo mode, the mod process rate must not exceed
  2865.      45.5kHz/2, or 22.75kHz. This is a limitation of the Sound Blaster. In mono,
  2866.      you can run up to 45.5kHz if you have the muscle to do so (typically
  2867.      requires a 486, and a DMAX: setting of at least 4). Buffer sizes above 4K
  2868.      matter most on slower machines.
  2869.  
  2870.      Adjusting the mod processing while playing is permitted, though it's
  2871.      recommended to do so only when not.
  2872.  
  2873.      Sample Use:
  2874.  
  2875.      struct SetModPack SMP;
  2876.  
  2877.      SMP.Func = SetIntRateMod;
  2878.      SMP.IntRate = 22000;     
  2879.      rez = RUCKDAC(&SMP);
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.                                                                               44
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.      SetSpeedMod         Func: 57       Pack: SetModPack
  2912.  
  2913.      Temporarily increases or decreases the playback speed of the mod file
  2914.      playing. The basic speed of a mod, with regard to this routine, is 6.
  2915.      However, at any particular point in the mod file this can change.
  2916.  
  2917.      The speed range is 1 to 15, with 1 resulting in fast play, and 15 resulting
  2918.      in a very slow play.
  2919.  
  2920.      Sample Use:
  2921.  
  2922.      struct SetModPack SMP;
  2923.  
  2924.      SMP.Func = SetSpeedMod;
  2925.      SMP.Speed = 4;          // increase play by 33% over norm
  2926.      rez = RUCKDAC(&SMP);
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.                                                                               45
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.      SetVolumeMod        Func: 58       Pack: SetModPack
  2978.  
  2979.      SetVolumeMod controls each of the four mod digital output channels.
  2980.      Normally they would all be set to maximum (255). In order to adjust channel
  2981.      volume, FastMod mode must be off.
  2982.  
  2983.      Sample Use:
  2984.  
  2985.      struct SetModPack SMP;
  2986.  
  2987.      SMP.Func = SetVolumeMod;
  2988.      SMP.VolCh1 = 255;
  2989.      SMP.VolCh2 = 255;
  2990.      SMP.VolCh3 = 255;
  2991.      SMP.VolCh4 = 255;
  2992.      rez = RUCKDAC(&SMP);
  2993.  
  2994.  
  2995.  
  2996.  
  2997.  
  2998.  
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.                                                                               46
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.      SetPositionMod      Func: 59       Pack: SetModPack
  3044.  
  3045.      Each mod file is composed of several tracks, known as patterns. Each
  3046.      pattern contains 64*4 notes (64 notes per channel). A mod file can contain
  3047.      up to 63 separate patterns, and can play up to 128 patterns in total
  3048.      (though any pattern can be made to repeat). SetPositionMod lets you move to
  3049.      the start of any pattern to be played (up to the number of patterns to
  3050.      play). The first pattern is pattern number 0. The last possible patter
  3051.      number is 127.
  3052.  
  3053.      Sample Use:
  3054.  
  3055.      struct SetModPack SMP;
  3056.  
  3057.      SMP.Func = SetPositionMod;
  3058.      SMP.Position = 0;          // restart play from the beginning
  3059.      rez = RUCKDAC(&SMP);
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.                                                                               47
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.      SetStereoMod        Func: 60       Pack: SetModPack
  3110.  
  3111.      Mod data files contain four channels of information. In mono playback mode,
  3112.      all four of these are combined to form a single digital output stream. In
  3113.      stereo mode (SB PRO only), you can select from three different combine
  3114.      modes. You can increase this to nine stereo combinations by setting the
  3115.      high bit of SMP.Stereo. If set, the left/right channels are reversed.
  3116.  
  3117.      Sample Use:
  3118.  
  3119.      struct SetModPack SMP;
  3120.  
  3121.      SMP.Func = SetPositionMod;
  3122.      SMP.Stereo = 1;          // 0=mono
  3123.      rez = RUCKDAC(&SMP);     // 1=LEFT:ch1+ch3  RIGHT:ch2+ch4
  3124.                               // 2=LEFT:ch1+ch4  RIGHT:ch2+ch3
  3125.                               // 3=LEFT:ch1+ch2  RIGHT:ch3+ch4
  3126.                               // &H8000 + mode then LEFT <-> RIGHT, e.g.,
  3127.                               // &H8001=LEFT:ch2+ch4  RIGHT:ch1+ch3
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.  
  3134.  
  3135.  
  3136.  
  3137.  
  3138.  
  3139.  
  3140.  
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.                                                                               48
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.      SetFastMod          Func: 61       Pack: SetModPack
  3176.  
  3177.      Mod files require lost of CPU power and lots of CPU attention. The most
  3178.      often executed code performs 4 BPTR IMUL instructions every tick of a
  3179.      process clock (10,000 times/sec if that is the process rate selected).
  3180.      Multiply on the 8088 is a very time consuming operation. If an 8088-based
  3181.      computer is to play mod files, these multiplies must be sped up. SetFastMod
  3182.      performs this task by implementing an alternate method. Note that with
  3183.      FastMod mode enable, some mod files may sound odd.
  3184.  
  3185.      The SliceAdj instructs the DMA buffer fill code to perform more than one
  3186.      mix per interrupt. By increasing this number you reduce the interrupt-
  3187.      latency time wasted (since more mod data is processed per interrupt) but
  3188.      you also decrease the amount of time given to other tasks (tasks other than
  3189.      mod playback). Fast CPUs have no problem keeping the DMA buffers full, so
  3190.      even a large SliceAdj will have little of any impact on these machines.
  3191.      However, on slow machines where the DMA buffers are constantly needing to
  3192.      be filled (where neither DMA buffer is ever filled) a SliceAdj above 1 may
  3193.      be desirable. Typically, though, the default of 1 works fine.
  3194.  
  3195.      Sample Use:
  3196.  
  3197.      struct SetModPack SMP;
  3198.  
  3199.      SMP.Func = SetFastMod;
  3200.      SMP.FastMode = -1;      // 0=normal, 1=fast mode enabled, -1 to skip
  3201.      SMP.SliceAdj = 32;      // DMA buffer fill count (1-4096, default=1)
  3202.      rez = RUCKDAC(&SMP);
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.                                                                               49
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.      Appendix A. Tips and Tricks.
  3242.  
  3243.      See the RUCKUS-MIDI documenation.
  3244.  
  3245.  
  3246.  
  3247.  
  3248.  
  3249.  
  3250.  
  3251.  
  3252.  
  3253.  
  3254.  
  3255.  
  3256.  
  3257.  
  3258.  
  3259.  
  3260.  
  3261.  
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.                                                                               50
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.      Appendix B. Pack Structure.
  3308.  
  3309.      #pragma pack(1)
  3310.  
  3311.      int __far __pascal RUCKDAC(void __far *datapack);
  3312.  
  3313.      #define SysInfoDac      0
  3314.      #define InitDac         1
  3315.      #define ExitDac         2
  3316.      #define AtExitDac       3
  3317.      #define LoadDac         4
  3318.      #define PlayDac         5
  3319.      #define RecordDac       6
  3320.      #define StoreDac        7
  3321.      #define EndDac          8
  3322.      #define PauseDac        9
  3323.      #define DeallocDac      10
  3324.  
  3325.      #define SetAllDac       20
  3326.      #define SetVolumeDac    21
  3327.      #define SetIntRateDac   22
  3328.      #define SetPriorityDac  23
  3329.      #define GetBufferDataDac 28
  3330.      #define GetBytePosDac   29
  3331.  
  3332.      #define SetAllSBP       30
  3333.      #define SetVolMainSBP   31
  3334.      #define SetVolVocSBP    32
  3335.      #define SetLevelMicSBP  33
  3336.      #define SetLevelCDSBP   34
  3337.      #define SetLevelLineSBP 35
  3338.      #define SetFilterOutSBP 36
  3339.      #define SetFilterInSBP  37
  3340.      #define SetSourceSBP    38
  3341.      #define SetStereoSBP    39
  3342.  
  3343.      #define SetSpeakerSB    40
  3344.      #define GetMixerRegSBP  48
  3345.      #define GetDacSB        49
  3346.  
  3347.      #define ExitMod         50
  3348.      #define AtExitMod       51
  3349.      #define LoadMod         52
  3350.      #define PlayMod         53
  3351.      #define EndMod          54
  3352.      #define PauseMod        55
  3353.      #define SetIntRateMod   56
  3354.      #define SetSpeedMod     57
  3355.      #define SetVolumeMod    58
  3356.      #define SetPositionMod  59
  3357.      #define SetStereoMod    60
  3358.      #define SetFastMod      61
  3359.      /* current highest function is 61 */
  3360.  
  3361.  
  3362.                                                                               51
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.      struct DeallocPack {    /* DP */
  3375.       unsigned Func;
  3376.       int Stat;
  3377.       unsigned HandSeg;      /* RUCKUS allocates either XMM handle/DOS para */
  3378.       unsigned TypeFlag;     /* 0=DOS para, 1=XMS handle */
  3379.      }; /* 8 */
  3380.  
  3381.      struct GetDataPack {    /* GDP */
  3382.       unsigned Func;
  3383.       int Stat;
  3384.       unsigned long BytePos; /* current byte relative base ptr */
  3385.       char __far *BufferPtr; /* far pointer to buffer to fill with data */
  3386.       long StartPos;         /* start get at this offset relative BufferPtr */
  3387.       unsigned BufferCnt;    /* bytes to fill (2-65520) */
  3388.       unsigned MixerReg;     /* SBPro mixer register to get */
  3389.      }; /* 20 */
  3390.  
  3391.      struct InitPack {       /* IP */
  3392.       unsigned Func;
  3393.       int Stat;
  3394.       unsigned DeviceID;     /* 0=SPKR,1=LPTDAC,2=DSS,4=SB,5=SBPro */
  3395.       unsigned IOport;
  3396.       unsigned IRQline;
  3397.       unsigned DMAch;
  3398.       unsigned Flags;        /* see Appendix D. */
  3399.       void __far *InfoPtr;     /* ret:far ptr to dac info */
  3400.       void __far *DacExitPtr;  /* ret:far ptr to dac's ExitDac routine */
  3401.       void __far *ModExitPtr;  /* ret:far ptr to mod's ExitMod routine */
  3402.      }; /* 26 */
  3403.  
  3404.      struct LoadPack {       /* LP */
  3405.       unsigned Func;
  3406.       int Stat;
  3407.       void __far *FilenamePtr;/* far ptr to filenameZ to load */
  3408.       unsigned long StartPos; /* offset into file to start load at */
  3409.       unsigned long LoadSize; /* number of bytes to load (or 0 for autosize) */
  3410.       int XMMflag;            /* if <> 0 use XMS for load */
  3411.       int XMMhandle;          /* ret:XMS handle, or */
  3412.       void __far *LoadPtr;    /* ret:DOS seg:offset (offset always 0) */
  3413.      }; /* 24 */
  3414.  
  3415.      struct PlaybackPack {   /* PBP */
  3416.       unsigned Func;
  3417.       int Stat;
  3418.       unsigned Mode;         /* mode (0=int FG,1=BG,2=DMA,3=DMA+BG for mod) */
  3419.       unsigned XMMhandle;    /* if <> 0 this XMM handle used regardless */
  3420.       void __far *LoadPtr;   /* seg:off to start of data to play */
  3421.       unsigned BufferSize;   /* size of DMA buffer for mod playback */
  3422.      }; /* 14 */
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.                                                                               52
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.  
  3440.      struct PausePack {      /* PP */
  3441.       unsigned Func;
  3442.       int Stat;
  3443.       unsigned Pause;        /* 0=unpause else pause */
  3444.      }; /* 6 */
  3445.  
  3446.      struct RecordPack {     /* RP */
  3447.       unsigned Func;
  3448.       int Stat;
  3449.       unsigned SampleRate;
  3450.       int XMMhandle;         /* -1 auto XMS (ret here) else use this handle */
  3451.       void __far *RecordPtr; /* seg:off of buffer to store (0 for auto-store) */
  3452.       unsigned long RecordBytes; /* bytes to record */
  3453.       unsigned StereoFlag;   /* stereo flag */
  3454.      }; /* 18 */
  3455.  
  3456.      struct SaveDataPack {   /* SDP */
  3457.       unsigned Func;
  3458.       int Stat;
  3459.       void __far *FilenamePtr; /* far ptr to filenameZ to save */
  3460.       void __far *DataPtr;   /* pointer to start of data to save */
  3461.       unsigned FileType;     /* 1=VOC,2=WAV */
  3462.       unsigned XMMhandle;    /* XMS handle of data to save (0 if DOS data) */
  3463.      }; /* 16 */
  3464.  
  3465.      struct SetPack {        /* SP */
  3466.       unsigned Func;
  3467.       int Stat;              /* (if volume=0 SB speaker off'ed else on'ed) */
  3468.       unsigned Volume;       /* volume (left ch=MSB,right=LSB) (0-127,0-127) */
  3469.       unsigned IntRate;      /* playback interrupt rate (5000-23000) */
  3470.       unsigned Priority;     /* priority level (0-2, default=1) */
  3471.      }; /* 10 */
  3472.  
  3473.      struct SetModPack {     /* SMP */
  3474.       unsigned Func;
  3475.       int Stat;
  3476.       unsigned VolCh1;       /* channel volume (0-255) */
  3477.       unsigned VolCh2;       /* channel volumes adjustments made only */
  3478.       unsigned VolCh3;       /*  if FastMode=0 */
  3479.       unsigned VolCh4;
  3480.       unsigned Stereo;       /* playback mode (0=mono,stereo 1,2,3) */
  3481.       int FastMode;          /* fast playback (0=normal,1 fast,-1 skip) */
  3482.       unsigned IntRate;      /* playback interrupt rate (5000-45500) */
  3483.       unsigned Position;     /* pattern list position (0-patterns to play) */
  3484.       unsigned Speed;        /* temp playback speed (1-15,default=6,15=slow) */
  3485.       unsigned SliceAdj;     /* slice adj (1-4096,default=1) set via FastMod */
  3486.      }; /* 24 */
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.                                                                               53
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.  
  3506.      struct SetProPack {     /* SPP */
  3507.       unsigned Func;
  3508.       int Stat;
  3509.       unsigned Volume;       /* volume (low=right;0-15, high byte=left;0-15) */
  3510.       unsigned VolVoc;
  3511.       unsigned VolMic;       /* (mono only, 0-7) input level */
  3512.       unsigned VolCD;        /* input level (0-15,0-15) */
  3513.       unsigned VolLI;        /* input level (0-15,0-15) */
  3514.       unsigned FilterOut;    /* 0=filter off, 1=filter on */
  3515.       unsigned FilterIn;     /* 0=filter off, 1=3.2kHz, 2=8.8kHz */
  3516.       unsigned SourceIn;     /* 0=mic,1=CD,2=line */
  3517.       unsigned StereoIn;     /* 0=mono,1=stereo record */
  3518.      }; /* 22 */
  3519.  
  3520.      struct XitPack {        /* XP */
  3521.       unsigned Func;
  3522.       int Stat;
  3523.      }; /* 4 */
  3524.  
  3525.      struct SysDev {         /* SD (used by SysInfoPack below) */
  3526.       int Device;            /* =1 device available */
  3527.       unsigned Port;
  3528.       unsigned IRQ;
  3529.       unsigned DMA;
  3530.       unsigned Flags;        /* bit4=MIDI/3=XMS/2=DMA/1=REC/0=PLAY */
  3531.      }; /* 10 */
  3532.  
  3533.      struct SysInfoPack {    /* SIP */
  3534.       unsigned Func;
  3535.       int Stat;
  3536.       unsigned CPU;          /* CPU class (88,286,386,486) */
  3537.       unsigned CPUmode;      /* 0=real mode,1=PM,2=PM w/paging */
  3538.       unsigned MHz;          /* approx speed (5,20,33) */
  3539.       struct SysDev SD[6];
  3540.      }; /* 70 */
  3541.  
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.                                                                               54
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.      Appendix C. Compiler, Linker, and Call Use.
  3572.  
  3573.      Consult your development system's documentation on the use of external
  3574.      library files. For call use, see the example X*.c files.
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.  
  3599.  
  3600.  
  3601.  
  3602.  
  3603.  
  3604.  
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.                                                                               55
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.      Appendix D. RUCKUS-DAC Data Area.
  3638.  
  3639.      To access the DAC data area in your code:
  3640.  
  3641.           extern struct DacDataArea pascal DACDATA;
  3642.           :
  3643.           printf("DACDATA DeviceID is %u", DACDATA.DeviceID);
  3644.  
  3645.      /* dac data area structure */
  3646.  
  3647.      #pragma pack(1)  /* ALL Ruckus data structures MUST be byte-aligned */
  3648.  
  3649.      struct DacDataArea {
  3650.       unsigned DeviceID;     /* 0   ;device ID */
  3651.       unsigned IOport;       /* 2   ;port of device */
  3652.       unsigned IRQ;          /* 4   ;IRQ of device */
  3653.       unsigned DMA;          /* 6   ;DMA of device */
  3654.       unsigned Flags;        /* 8   ;bit0=1 use DOS UMB memory */
  3655.                              /*     ;bit1-3 reserved */
  3656.                              /*     ;bit4=1 force SBPro if SB15 (DSPtype=3) */
  3657.                              /*     ;       (but DSPversion remains same) */
  3658.                              /*     ;bit5=1 force XMS2 to be used */
  3659.                              /*     ;bit6=1 force dev speaker on until exit */
  3660.                              /*     ;bit7=1 force passed parms to be used */
  3661.                              /*     ;       Following values are ret bits */
  3662.                              /*     ;bit8=1 paging in force, no UMBs */
  3663.                              /*     ;bit9-15 reserved */
  3664.       unsigned End;          /* 10  ;=1 end of play (dac, not mod) */
  3665.       unsigned Pause;        /* 12  ;=1 pause play */
  3666.       unsigned EndOfMod;     /* 14  ;=1 end of mod play */
  3667.                              /*     (when dac@end AND dac@endmod   */
  3668.                              /*     ;both are 1 then play is done) */
  3669.       unsigned MemDOS;       /* 16  ;DOS memory available (in K) */
  3670.       unsigned MemXMM;       /* 18  ;XMS memory available (in K) */
  3671.       unsigned Type;         /* 20  ;digital file type (1=VOC,2=WAV,3=MOD) */
  3672.       unsigned MemUsed;      /* 22  ;memory used for last file load (in K) */
  3673.       unsigned SampleRate;   /* 24  ;sample rate currently playing */
  3674.       unsigned Stereo;       /* 26  ;stereo playback (data is stereo) */
  3675.       unsigned long VocLen;  /* 28  ;length of voc block (only current block) */
  3676.       void __far *VocPtrPtr; /* 32  ;pointer to pointer->current data */
  3677.       unsigned long RecordLen;/*36  ;length of recorded data */
  3678.      }; /* 40 */
  3679.  
  3680.      #pragma pack()
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.                                                                               56
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.      /*
  3704.      To access the MOD data area in your code:
  3705.  
  3706.           extern struct ModDataArea pascal MODDATA;
  3707.           :
  3708.           printf("MODDATA Type is %u", MODDATA.Type);
  3709.      */
  3710.  
  3711.      #pragma pack(1)  /* ALL Ruckus data structures MUST be byte-aligned */
  3712.  
  3713.      struct ModDataArea {
  3714.  
  3715.       void near *chInfoPtr;/* -2  ;near ptr to channel info (not listed) */
  3716.  
  3717.       unsigned Type;         /*  0  ;mod type (15 or 31 samples) */
  3718.       unsigned Samples;      /*  2  ;number of instrument samples in mod */
  3719.       unsigned HeaderSeg;    /*  4  ;header segment (aka sample info) */
  3720.       unsigned PatternSeg;   /*  6  ;pats' segment (1 to pats2play 1K pats) */
  3721.       unsigned SampleSeg[31];/*  8 (+62) ;list of sample segments */
  3722.  
  3723.       unsigned Stereo;       /* 70  ;=1 then play stereo (only SBPro can set) */
  3724.       unsigned FastMode;     /* 72  ;=1 then channel volume adjusts disabled */
  3725.  
  3726.       unsigned PatListPos;   /* 74  ;byte pos within mod@patterList (0-127) */
  3727.       unsigned NotePatPos;   /* 76  ;note pos within pattern 1K area (0-1008) */
  3728.                              /*     ;pattern#=patternList(patListPos) */
  3729.                              /*     ;note is at offset (pat#*1024)+notePatPos */
  3730.                              /*     ;-- in segment mod@patternSeg */
  3731.       unsigned HiPattern;    /* 78  ;highest pattern # to play/+1!/ (0-63) */
  3732.       unsigned Pats2play;    /* 80  ;pats to play (direct DOS file load here) */
  3733.       char PatternList[128]; /* 82  (+128) ;pattern positions (to here) */
  3734.       char MKoverflow[6];    /*210 (+6)   ;overflow for 31-instr patpos read */
  3735.  
  3736.       unsigned MemUsed;      /*216 ;DOS mem needed by mod file loaded (paras) */
  3737.       unsigned long VS;      /*218 ;times VS handler entered (50Hz rate) */
  3738.      }; /* 222 */
  3739.  
  3740.      #pragma pack()
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.                                                                               57
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.      Appendix Z. Ordering Information, License Agreement and Product Support.
  3770.  
  3771.      To order you must you the order form included with the distribution files.
  3772.      Its filename is !ORDER.FRM. Orders made without this form may be delayed.
  3773.  
  3774.      There are two RUCKUS packages available. The PERSONAL DEVELOPER version is
  3775.      for the hobby-programmer while the PROFESSIONAL version is for the
  3776.      professional programmer.
  3777.  
  3778.      The PERSONAL DEVELOPER version is for persons that are not creating
  3779.      programs for distribution to others. With the PERSONAL DEVELOPER license
  3780.      you may not distribute any programs you create with RUCKUS. In addition, a
  3781.      sign-on banner is issued once, displaying the RUCKUS copyright and license
  3782.      restriction.
  3783.  
  3784.      The PROFESSIONAL version has no distribution restrictions on end-user
  3785.      programs you create with RUCKUS. The PROFESSIONAL license provides you with
  3786.      the right to create all the end-user programs royalty-free. You also have
  3787.      direct access to the latest version of RUCKUS free-of-charge by way of my
  3788.      support BBS and the RUCKUS Developer's Conference there. No sign-on banner
  3789.      is issued.
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.                                                                               58
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.      License Agreement
  3836.  
  3837.      Before using this software you must agree to the following:
  3838.  
  3839.      1. You are not allowed to operate more than one (1) copy of this software
  3840.      package at one time per license. This means that if you have 10 programmers 
  3841.      that COULD possibly use the RUCKUS library at the same time, you must also  
  3842.      have ten (10) RUCKUS licenses. 
  3843.  
  3844.      2. You are not allowed to distribute non-executable code containing RUCKUS 
  3845.      code. This means that you are not allowed to redistribute RUCKUS code as    
  3846.      another .LIB, for example. Also, if RUCKUS code is to be contained in a    
  3847.      Dynamic Link Library (DLL) then it must be part of a stand-alone product. 
  3848.      This means that you cannot provide a .DLL containing RUCKUS code if that    
  3849.      .DLL is to be used as a programming library for other programmers. If you   
  3850.      wish to distribute non-executable code containing RUCKUS code you must    
  3851.      obtain written permission from the author.
  3852.  
  3853.      3. This license grants you the right to use the RUCKUS library code on a   
  3854.      royalty-free basis, except when the license is the PERSONAL DEVELOPER, in
  3855.      which case you may not distribute any program in which RUCKUS has been
  3856.      used.
  3857.  
  3858.      4. RUCKUS is owned by the author, Cornel Huth, and is protected by United  
  3859.      States copyright laws and international treaty provisions. You are not    
  3860.      allowed to make copies of this software except for archival purposes.
  3861.  
  3862.      5. You may not rent or lease RUCKUS. You may not transfer this license
  3863.      without the written permission of the author. If this software is an update
  3864.      or upgrade, you may not sell or give away previous versions.
  3865.  
  3866.      6. You may not reverse engineer, decompile, or disassemble this software.
  3867.  
  3868.      7. There are no expressed or implied warranties with this software.
  3869.  
  3870.      8. All liabilities in the use of this software rest with the user.
  3871.  
  3872.      9. U.S. Government Restricted Rights. This software is provided with    
  3873.      restricted rights. Use, duplication, or disclosure by the Government is    
  3874.      subject to restrictions as set forth in subparagraph (c)(1)(ii) of the    
  3875.      Rights in Technical Data and Computer Software clause at 52.227-7013.    
  3876.      Manufacturer is Cornel Huth/6402 Ingram Rd/San Antonio, TX 78238.
  3877.  
  3878.      This agreement is governed by the laws of the state of Texas.
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.                                                                               59
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.      Product Support
  3902.  
  3903.       BBS support telephone: 1(210)684-8065. V.32bis (1200-14.4k bps)
  3904.       Hours: Monday through Friday, 5pm to 9am next morning
  3905.              Weekend hours are 1pm to 9am next morning.
  3906.              All times USA Central [-0600/-0500]
  3907.  
  3908.      E-mail:
  3909.  
  3910.      Internet: chuth@lonestar.utsa.edu -or-
  3911.                cornel.huth@LChance.sat.tx.us -or-
  3912.                cornel.huth@p8.f800.n387.z1.fidonet.org
  3913.       Fidonet: 1:387/800.8
  3914.  
  3915.      PROFESSIONAL version licensees have _free_ access to all future RUCKUS
  3916.      updates AND upgrades via the RUCKUS Developer's Conference on The Fortieth
  3917.      Floor BBS (1(210)684-8065). PERSONAL DEVELOPER licensees have restricted
  3918.      access to in-version maintenance updates at no charge.
  3919.  
  3920.      End of the RUCKUS-DAC DOCUMENT. See also the RUCKUS-MIDI DOCUMENT.
  3921.